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Introduction ARC 


The Archimedes Basic Compiler — ABC for short — will transform your 
BASIC V programs into super-fast ARM machine code which can be saved 
and then used at any time, regardless, the BASIC ROM or ABC is present. 
ABC generates totally stand-alone machine code. 


But ABC also goes very much further. By using special, but very simple 
commands embedded in REM statements it is also possible to turn the same 
BASIC programs into relocatable modules that can subsequently be loaded 
into the Relocatable Module Area (RMA) and used as * commands from | 
within any other application. Thus, from BASIC, it would be possible to add 
special and quite unique facilities to further enhance the power of your 
Archimedes. 


The Archimedes Basic Compiler also gives your programs more speed. By 
converting them into machine code, they are running in the Archimedes’ 
native language and unlike a BASIC program do not have to go through an 
interpretive process each and every time they are run. As such some quite 
phenomenal speed increases are possible, and a 4000% (forty-fold) increase 
in speed is achievable depending on the program you are compiling. 


Read Me! 


The Examples disc contains a file which may contain further information 
about ABC which has come to light since the release of the manuals. To 
read this insert the Examples disc in drive 0 and type: 


*BASIC 
*README 


You will be asked if you want a hard copy of the text. Respond with a Y if 
you do, and ensure your printer is attached and on-line. If you do not want 
a hard copy, the text will be displayed on screen. 


Registration 


Your ABC pack contains a registration card. Please fill this in and return it 
to Dabs Press. This has a number of advantages for you as an ABC user: 
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Free Upgrades All registered users will be entitled to upgrades of 
ABC as and when they become available. These will be 
totally free of charge to registered users. 


_ Technical Support Use of our ABC Technical Support Services will be 
available to all registered users. See below. 


Newsletter It is hoped to produce a Newsletter from time to time. 
Registered users will automatically receive this free of 
charge 


Getting the Best from ABC 


To get the very best from ABC, make yourself as familiar as possible with 
the pages in this User Guide, and be aware of the contents of the ABC 
Reference Guide. This will allow you to find the relevant information 
quickly should you encounter any problems during the compilation of a 
program. 


Remember that ABC is a compiler and is not designed to be a programming 
aid. Write all your programs in the BASIC Editor first, and test and debug 
them fully under BASIC, which has an excellent range of error messages. 
Once the program is working to your satisfaction, load ABC and then 
compile it. 


Technical Support Service 


If you are having programming difficulties and cannot get a program to 
compile, our ABC Technical Support Service will be of invaluable help and 
is available to all registered users of ABC for just £5. 


You shculd supply the following information: 
¢ Brief, but concise details of your problem 
¢ Details of hardware 
e Disc containing the program in question where appropriate 


¢ A stamped address envelope for return of your disc and reply 
¢ Day and evening phone number 


You should also include a cheque or postal order for £5 payable to Paul 
Fellows and address your query to: 


ABC Query, 


Dabs Press, 5 Victoria Lane, Whitefield, 
Manchester, M25 6AL 
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Please note: this is a postal service only and limited to registered users of 
ABC. It is conducted by Paul Fellows. It is not conducted on the Dabs Press 
premises and it is not a telephone service so please refrain from calling or 
phoning as we will be unable to assist. The £5 charge covers single problem 
solution if your problem is compound or of a greater complexity a quote 
will be given. Queries of this nature which do not enclose the items 
requested will be returned without service. 


The service is not for bug-fixing. If you should happen to find a bug in ABC, 
we will of course attempt to fix it, and supply you with a new version free 
of charge. Also general problems such as corrupted discs etc. should be 
reported to Dabs Press, and may be made by telephone. 


Royalties 


Programs of a commercial nature which are compiled with the Archimedes 
Basic Compiler are not subject to a royalty payment. However we do ask. 
that you acknowledge the use of ABC in any documentation or within the 
software itself. The suggested wording is “Program compiled with the 
Dabs Press Archimedes Basic Compiler”. 


Network Licences 


Network licences are available for ABC at a cost of twice the recommended 
retail price of the Compiler. Please apply to Dabs Press for a licence. 
Additional manuals are available for a small charge. 


Sell Us Your Programs! | 


If you develop a program which shows off the many features of ABC then 
we would like to see it for possible inclusion in our Newsletter or Examples 
disc. Please send us a copy with explanatory notes and documentation. All 
contributions used will be paid for. 


1 : Getting Started 


The ABC Compiler disc includes an installation program which will 
automatically create a tidy and efficient environment from which you can 
load and transform you BASIC V programs into ARM machine code. If you 
have a hard disc then the installation program will copy the files onto this 
for you. If you have a floppy disc-based system, it will produce a working 
copy of the program for you allowing you to file the master disc away for 
future reference should your working disc becomes corrupted or unusable. 





However, if you are itching to try the software straight away, you can do 
so. Here's what you do: 


Insert the ABC Compiler disc into drive 0 and type: 
*MOUNT 0 
Then type: 
* ABC | 
This sets up an environment from which.ABC can be used. Next type: 


*COMPILE WELCOME OBJECT 


The ABC screen windows will appear. Press RETURN twice to confirm the 
file names displayed and to instigate the compilation. As the 'Welcome'’ 
program compiles it will be listed in the lower window. 


During compilation you will notice that the horizontal bar will fill up with 
different shades of grey as the various phases of compilation proceed. 
When the compilation is over, this bar will be completely white. 


Assuming all has gone well, you will be asked if you want to run the 
compiled object program. Answer by typing: Y 


The program will be run giving a friendly message. 


That's it. You've used ABC for the very first time, and that's all there is to 
it. It really is as simple as ABC! 


Now that you have tried the software, it is in your best interests to 
complete the installation procedure. Don't forget to fill in the Registration 
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Card as without this we will be unable you give you any technical support. 
It will also ensure that you get any upgrades of the software free of charge. 


System Configuration 


You may find it necessary to adjust the software configuration of your 
Archimedes in order to provide the best possible environment for running 
ABC. In particular you may like to set up the amount of memory which is 
reserved for Sprites and for Relocatable Modules. You will need to reserve 
at least 8k of memory for sprites and 32k for Relocatable Modules (RMs). 
These can be set up using the *CONFIGURE command, details of which will 
be found in the documentation which accompanies your Archimedes. 


You may also find that configuring the Archimedes to start up in BASIC or 
the '* command interpreter is more convenient than the default, which is 
to enter the Desktop. This can be done by typing: 


*CONFIGURE LANG. 0 


to enter the '** command prompt on reset. 


The command to set BASIC as the default is: 


*CONFIGURE LANG. 4 


on all current versions of the Archimedes. After you have altered the 
configuration of your machine you will need to perform a hard reset by 
pressing CTRL-BREAK to make the system take note of the new setting. 


The ABC software does not attempt to modify the configuration of your 
machine automatically, because such action inevitably causes problems 
when unusual hardware combinations or new operating system versions 
are encountered. | 


The following configurations are therefore recommended for your 
Archimedes for use with ABC at the time of going to press, however these 
are so py to change and you should look at the README file on your ABC 
Examples disc for any extra/further information: 


*CONFIGURE RMASIZE 4 
*CONFIGURE SPRITESIZE 1 
*CONFIGURE SCREENSIZE 0 
*CONFIGURE LANGUAGE 3 


ABC User Guide 


Module or RAM? 


ABC is implemented as a fully relocatable module which loads into the 
Relocatable Module Area (RMA) when first run. To clear ABC issue the 
command: 


‘*RMKILL ABCompile 


The advantage of using ABC as a module is that the compiler does not 
have to be loaded each and every time you wish to compile a program. 


There may be times when you wish to use a RAM based version of ABC and 
therefore a *RUNable version of ABC is included on the Compiler disc in 
the Library directory under the filename “RAMcomp”. 


Installing ABC 


The very first thing which you must do with ABC is to install a working 
copy of the compiler software. This installed copy will be the one which you 
will use to compile programs. You can install a copy onto another floppy 
disc or onto your hard disc if you have one. In order to make this as 
painless as possible, a special install program has been written and placed 
on the ABC Compiler disc. Once installed you should put the original ABC 
Compiler disc in a safe place. 


Note: The installation procedure installs the Module version of ABC. If you 
wish to install the RAM-based version of ABC then please refer to the 
README file notes on the Examples disc. See the Introductory section of this 
User Guide for further information. 


Please remember that the ABC software is subject to copyright and so you 
are only allowed to make copies for your own personal use. It is a criminal 
offence to give away unauthorised copies and will be treated as such. 


Installing onto a Floppy Disc — 


To install ABC onto a floppy disc you will need to first format a disc. It is 
imperative that you use the 800k 'D' format for this disc so as to allow 
yourself space for your own programs as well as for the ABC software. To 
do this you should type: 


PEQnene 30>) 


and, with a new floppy disc in drive 0, answer Y to the prompt: ‘Are you 
sure?’. 
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You now have to give this disc a name. In the text which follows 
‘ABCwork’ is used. With the blank disc in drive 0 type: 


*NAMEDISC :0 ABCwork 


You do not have to call the disc ‘ABCwork’, any other unique name will do. 
Once this is done, remove the disc from the drive and insert the original 
ABC compiler disc. Type: 


*MOUNT 0 


And then run the install program by typing: 
* INSTALL 


The install program will run and produce a screen display with three 
windows. In the window at the top left of the screen, there are two boxes 
into which you will have to type information concerning the installation. 


You must perform the install process. The distribution disc is in 640k format 
and does not have sufficient space to run the compiler correctly. 


The first box is labelled ‘directory’. Here, you should enter the full name of 
the directory into which you would like to install the ABC system files. This 
directory will be created if does not already exist and the ABC system files 
will be copied into it. 


The default text which it contains is set up for installation onto a hard disc 
(drive 4). To install onto your working disc you should overwrite the 
default text with: 


-ABCwork.ABC1lib 


If you have used a different name for the working disc you must use the 
same name again here. You can choose a different directory name, “ABClib’ 
is just one sensible choice. 


If you make a mistake you can use the left and right cursor arrow keys to 
move back and forth and then retype the name. When used on its own the 
DELETE key deletes to the left; if you hold down SHIFT key and use DELETE 
then the character underneath the cursor will be deleted and text will be 
shuffled along from the right. When you are happy with the name, press 
RETURN. 


The second box is labelled ‘Command file’ — this is the name of the 
command you will use to start ABC running. Into this box enter the name 
of the command file which you wish the system to build. Again, the default 
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is set up for installation onto a hard disc. Floppy disc users should overtype 
this with: 


:ABCwork.ABC 

This gives the command file the name ‘ABC’ and places it in the root 
directory on your 'ABCwork' disc. You can edit this name as described 
above and you can even move back up to edit the directory name using the 
up-arrow cursor key. The down-arrow cursor key will return you to the 
command file box. When you are happy with the name, press the RETURN 
key. 

Copying the Files 


The install program will then try to copy the files from the original ABC 
disc to the working disc. If you are using a single drive system it will 
prompt you to change the disc as and when required. 


Creating the Command File 


Once the files have been copied the install program will create a command 
file which you will use to start ABC This process is entirely automatic but 
the mechanism is described later in this chapter. 


Installing ABC onto a Hard Disc 


The procedure for installing ABC onto a hard disc is quite straightforward. 
The hard disc should of course already be formatted—if not consult the 
documentation supplied with it. 


To install ABC onto your hard disc insert the original ABC Compiler disc 
into drive 0 and type: 


*MOUNT 0 
Then type: 
| * INSTALL 
The install program will run and produce a screen display with three 


windows. In the window at the top left of the screen there are two boxes 
into which you will have to type information concerning the installation 


The first box is labelled ‘directory’. Here, you should enter the full name of 
the directory into which the ABC system files will be placed. The directory 
will be created if does not already exist. By detault it contains the text 


>4.S$.ABClib 


iZ 
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If your hard disc is drive 5 then you will have to edit the name accordingly. 
If you have given your hard disc a disc name, this may be used instead of 
the drive number. When you are happy with the name, press RETURN. 


The second box is labelled ‘command file’. This the name of the file which 
you will use to start ABC running. Into this box you should enter the name 
of the command file which you wish the system to build. The default is set 
up for installation onto drive 4 in the library directory, with the file name 
‘ABC’, ie, 

:4.Library.ABC 


You can edit this name as described above and you can even move back up 
to edit the directory name using the up-arrow cursor key. The down-arrow 
cursor key will return you to the command file box. When you are happy 
with the name, press the RETURN key. 


Copying and Creating 


The install program will then try to copy the files from the ABC Compiler 
disc to the hard disc. Once the files have been copied the install program 
will create a command file which you will use to start the system up. 
Installation is now complete. 


The ABC Command File 


It is not necessary to understand the details of the ABC command file but it 
might be useful, particulary if you are trying to install the software in an 
environment which is not covered in this guide, for example onto a 
network fileserver. 


Essentially the command file performs three tasks. Firstly it sets up the 
system variable ‘ABC$PreFix’ to hold the directory name which was 
specified in the install procedure above. This prefix is then used at all times 
by the ABC system when it requires access to the different system files. 


Secondly it then loads (using ABC$prefix) the Floating Point Emulator 
package which will have been copied during the installation process into 
the given directory. 


Finally, the compiler module is loaded (or a command Alias is set up) so 
that all you need to do to run the compiler program is to type “COMPILE. 
The compiler then pulls in the run-time library and header code chunks and 
the file of icons, again using ABC$prefix for them all. 
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Once ABC has been installed onto either a working disc or your hard disc, 
you will need a BASIC program to compile! The simplest way to get one is to 
type one in. 


Enter BASIC by typing: 
*BASIC 


and enter the following short program: 


10 REM >Hello 
20 PRINT "Hello ABC User!" 


With the working disc in drive 0, type: 
*MOUNT 0 


followed by: 

SAVE 
The program will be saved as $.Hello on the working disc. You now have 
something to compile. 


Initialise the ABC software by typing the name of the command file (which 
you gave during the installation) as a *command. For example, if you 
called the command file ‘ABC’, as was suggested, type: 


*ABC 
You can now run the compiler by typing: 


* COMPILE 


The ABC Menu screen should now be displayed. It contains three separate 
windows, the functions of which are outlined below. A representation of 
the screen is shown on the next page. 
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The ABC Menu screen. 


Status Window 


This is the window in the top right hand part of the screen. It will usually 
contain the Dabs Press logo and copyright messages. However, ABC status 
messages — such as error messages — will be displayed in this window as 
and < they may occur. When a compilation is successfully completed 
ABC will display the size of the object code which has been produced and 
the length of time taken in this window. 


Listing Window 


This is the large window at the bottom of the screen and serves two 
ee. Firstly, it is used to list the BASIC program source text (unless 
inhibited) as it is compiled. If ABC finds an error, the offending line will be 
displayed here — with the faulty part highlighted if possible. 


The second function of this window is to allow Operating System '*' 
commands to be issued and to display any resulting output. For example, a 
catalogue of the files on disc can be obtained in this window. The section 
‘Star Commands’ describes how this can be done. 
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Control Window 


Situated at the top left of the screen, this window displays the Source and 
Object filenames, where they are to be buffered (either RAM or DISC), and 
also just how far ABC is through compiling the current program. This 
latter information is signified by means of a horizontal bar in the lower 
part of the window. This bar will change colour to show the progress of the 
various phases of the compilation as detailed in the following table. 


Colour Meaning 

Dark grey First pass 

Grey Second (optional) pass 
Light grey Third pass 

White Fourth and final pass 


The two boxes at the righthand side of the window are used to specify 
whether the files are to be brought entirely into RAM or whether they are to 
be accessed directly from the disc during compilation. Thus it is possible to 
compile a program entirely in RAM or to and from disc or a combination of 
both. Typically, you would use disc based compilation for very large BASIC 
programs which would be too large to hold entirely in RAM. Full details of 
this aspect of using the compiler are given in the section ‘Disc Buffering’. 
For the moment, all examples will assume that the default, RAM-to-RAM 
compilation, is used. 


To compile the ‘Hello’ program you must proceed as follows: 


1. Type in the name of the source program, in this case HELLO, into the 
box labelled ‘Source:’, remembering to press RETURN when the 
filename is complete. | 


2, The cursor will now have moved to the ‘Object: box. Type in the 
object filename. ABC will save the compiled program under this 
name. For example, ‘HelloObj’ 


_ Again, press RETURN when the name is complete. The default name is 
‘Object’. You can overtype this name if you wish. 


You should be careful to use a name which does not clash with any 
existing file on your disc. ABC will overwrite an existing file when the 
object file is saved. It is a good idea to get into the habit of using 
names ending in ‘Obj’ for object programs. Alternatively you could 
create a directory ‘Obj’ and call all your object programs ‘Obj-hello’ 
GtC. 
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3. The program will now be compiled and, if all goes well, the object 
code will be saved. You can then run the object program by typing y in 
response to the prompt ‘Run object code (Y/N)’ 


At any time you can press ESCAPE to abandon the current operation. You 
will be asked if you want to quit the compiler. Again answer Y or N. 


Using Directories 


It is a good idea to use separate directories for your source and object 
programs. For example, you could set up the following directory structure 
on your disc. 






The ABC system files will all be in the library directory which will have 
been created when the system was installed. You may create the ‘Source’ 
and ‘Object’ directories as follows: 


Floppy Disc Users: 
Insert the disc in drive 0 and type: 


*MOUNT 0O 
*CDIR Source 
*CDIR Object 


Hard Disc Users: 
Type: 


*MOUNT 4 


*CDIR Source 
*CDIR Object 


The source programs can then be copied into the source directory. 


Assuming you have created a structure like this, you can then enter the 
source filename as: 


ys 
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Source.Hello 


and the Object filename as: 
Object.Hello 
Of course, you can create more complicated structures, for example you 


“might wish to subdivide your source files into different catagories using 
subdirectories. 


If the filenames become too long to fit in the boxes provided by ABC, you 
can use the wildcard character '*' to abbreviate parts them. For example, 
the filename: 


Source.Demos.Graphics.Triangle 
could be shortened to: 
~ ie Pah, Etat Yo 
assuming this leads to an unambiguous route to the file! 


Note that you cannot use a wildcard for the final part of the object 
filename. The directory parts can be shortened but the actual filename must 
be given in full. 


An alternative method of using a directory structure would be to go into 
the source directory using *DIR. For example: 


“DIR Sources. Demos.Graphics 
The source filename can then be given as: 
Triangle 


It will then be necessary to refer to the object file using the full name 
starting with '$'. For example: 


$.Obj*. Triangle 


Using Multiple Floppy Discs 


If you are using floppy discs, you will probably find that the working disc 
becomes full quite quickly if it is used to store all the source and object 
programs as well as the system files. Fortunately, it is very 
straightforward to make use of two or even three floppy discs at once. For 
example, you might want to have source files on another disc and put 
object files on a third. How you go about doing this depends entirely on 
your particular setup, the various options are outline below. 
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Use with a Single Drive 


First of all you must format and name your additional discs. Place the disc 
which is to hold the source programs in drive 0 and type: 


*NAMEDISC :0 Sources 


(You don't have to call it Sources—any unique name will do!) Copy the 
source programs which you want to use onto this disc. 


Put the object disc in drive 0 and type: 


*NAMEDISC :0 Objects 
(Again any unique name will do.) 


You are now ready to go. Insert the working disc with the compiler on it 
and start up the compiler. The source filename should now be entered into 
the input box on the screen. Let's assume the source file is called "Hello". 
Type: 


-Sources.Hello 


and press RETURN. Now enter the object filename: 
:Objects .HelloObjy 


The use of the disc name prefix enables the system to prompt you to swap 
discs. Press RETURN again to start the compilation. The Compiler will try to 
load the source program and fail because the wrong disc is in the drive. It 
will prompt you to insert the correct disc. and ask you to press a key when 
you have done so. Put the Sources disc in and press a key. The compilation 
should proceed through all the passes and then the compiler will try to save 
the object file. Again you will be prompted to change the disc. Put in the 
Objects disc and press a key. 


Finally the compiler will ask you if you want to run the object code 
straightaway. Press y to run it or N to get ready to compile another 
program. | 


Use with Dual Floppy Drives 
Proceed exactly as for a single drive. 


The system is intelligent in that if you have two drives and you refer to a 
disc by name it will use it whichever drive it is in. So name the discs and 
when it asks for a disc, just push it into whichever slot you like. The 
machine keeps track of which discs are present automatically! 
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Use with Hard and Floppy Discs 


In general, when using a hard disc, you will be able to hold all your files on 
it at once. However, there may be occasions when you want to compile to 
or from a floppy disc. This is simply accomplished by referring to the file(s) 
using the drive number prefix, or the disc name. 


For example, to compile a source program called ‘Hello’ on a floppy disc in 
drive 0 using the ABC system on a hard disc (drive 4) type: 


*MOUNT 4 
* ABC 


to initialise the ABC environment. Then type: 
* COMPILE 


to run the compiler. 
The source filename should then be entered as: 
| :0.Hello 


Compilation will then proceed as usual. 


Giving Filenames on the Command Line 


It is possible to supply the source or both the source and object filenames on 
the command line. For example: | 


*COMPILE SOURCE OBJECT 


will cause the strings SOURCE and OBJECT to appear in the appropriate boxes 
in the control window. Pressing RETURN twice will then start the 
compilation process. 


Star Commands 


ABC allows easy access to the Operating System '*' commands whilst the 
filenames are being entered. To issue a star command, hold down the ALT 
key and type a ™' (either from the numeric keypad or by using SHIFT-8). A 
“ prompt will appear in the lower window and you can enter your 
commands. Of course, you may issue any command you like at this stage 
but you should be aware that some operations (for example *COPpy when 
used with the Q option) will corrupt memory and so will prevent the 
compiler from continuing. 
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After each command has been given the prompt will reappear. When you 
have finished, just press RETURN. The cursor will return to its original 
position. The contents of the lower window will not be removed until 
compilation starts, or you enter more commands. 


Disc Buffering 


The default method of compiling a program is to load the entire source 
program into an area of RAM in one go and then compile it into a second 
RAM area — this is handled automatically by ABC. When compilation is 
complete, the object file is created by saving this second RAM area in one 
go. This provides the fastest method of compiling a program. However, 
this method requires a very large amount of memory if the source program 
(and hence the object program) is large. To avoid this it is possible to 
compile the source program directly from the disc. Similarly the compiler 
can write the object code to a disc file as it is created, instead of holding it 
entirely in RAM. 


To use this technique, enter the source filename and then press TAB. The 
cursor will move to the right hand box containing the word RAM. Overtype 
this with the word DISC and press RETURN. The source program on disc will 
be read continuously during compilation. 


The same method is used to set DISC buffering for the object code. 


It is possible to use any combination of RAM and DISC, the maximum RAM 
saving being achieved by specifying both as DISC. If the source and object 
files are on separate discs (possibly with the system files on a third) ABC 
will prompt you for the various discs as and when they are required. 


If you specify RAM as the source program area and ABC cannot find the 
program — you may not have loaded it —- then ABC will look on disc for the 
file. If it locates it, then compilation will be carried out using the disc 
entirely, ie, as though DISC options had been selected. 


If you choose to keep the object file entirely in RAM then ABC attempts to 
choose a suitable size block of memory. The size of this block (the ‘object 
code limit') will be displayed in the listing window at the start of each pass. 
ABC is uses the size of the source file as a guide when choosing the amount 
to reserve. The formula which is used is: 


Size of object = 3*(Size of Source) + 16k 


The 16k is added to allow for the run-time library which is always added, 
even for the smallest program! Also when trying to work out if a program 
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will compile in RAM bear in mind that ABC itself resides in memory and 
allow 200k for this. 


This should be a fairly generous allowance but it is possible that the size of 
the object code turns out to be larger than this. If this happens the compiler 
will stop and give an error. It is possible to enter the amount of memory to 
reserve for.the object code directly. To do this, move the cursor into the box 
to the right of the Object Filename by using TAB and the up/down arrow 
key. Then type in the number of kilobytes that will be required. 


In general the object code will be larger than the source code. The 
expansion factor varies from just over one to about four, though it may be 
possible to construct examples where it lies outside this range. If the source 
program is well structured with indented loops etc, has long variable 
names and has lots of REM comments then a factor of nearly one should be 
expected. The other extreme is a program which has been ‘crunched’ by 
one of the automatic program compaction utilities. 
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ABC provides some special directives which are used to control the way in 
which the compiler treats the source program. These provide some very 
advanced features and full details are provided in the ABC Reference 
Guide. However they are introduced at this stage since they are referred to 
in the remaining sections of this guide and are used in many of the ABC 


program examples to be found on the Examples disc. 


It is important that BASIC programs can still be used under the BASIC 
interpreter and for this reason any Compiler Directives which are placed 
within the source program must be such that they are ignored by the 
interpreter. For this reason, ABC's directives take the form of specially 
constructed REM statements. The compiler recognises them as It reads 
through the program and takes note of them. A typical directive is: 


100 REM {NOESCAPECHECK } 


All ABC directives take this form, with a REM followed by some text 
enclosed in braces or curly brackets’ { }. The text must always be in upper 
case if ABC is to recognise it. | 


This example of a directive tells the compiler that, from this point in the 
program onwards, it is not to bother generating machine code to check for 
the ESCAPE key. This can make programs shorter and much faster. For 
example the standard ‘Sieve’ benchmark runs twice as fast if it is compiled 
with ESCAPE checking turned off. 


Often it is inconvenient to have to cope with the possibility of ESCAPE being 
pressed at any time, while,for example, an ERROR handler is being 
adjusted. This directive can be used in conjunction with its opposite: 


REM {ESCAPECHECK } 


to prevent the program taking note of ESCAPE until it is ready to do so. 
Other directives allow sections of programs to be ignored. For example: 
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Paw wie 
130 REM {COMPILE} 
140 ee 


Here, lines 110 and 120 will be skipped by ABC. A good use for these 
directives is for code designed to help you with debugging, such as PRINT 
statements. The debugging code would then be executed by the interpreter 
but ignored by the compiler. The section 'Hints and Tips' gives some 
interesting examples. 


_ A more flexible way to do this is to use the conditional directives. This 
_ allows a number of parts of a program to be included or left out according 
_ to the value of a constant set at the start of the program. For example, you 
might want to produce two versions of a program in different languages, 
such as ENGLISH and GERMAN. Unfortunately, it is not possible to make use 
of this technique and still retain compatibility with the BASIC interpreter. 


10 DEF ENGLISH = 0 


100. REM {. IF ENGLISH. } 

L100 PRINT “Goodnye |” 

L120 REM’? SLSe° 7 

130 PRINT “Auf Weidersehen !” 
140. REM. {ENDIF } 


Full details of this technique are found in the ABC Reference Guide. 


The next chapter describes how compiler directives are used to control the 
production of relocatable modules and includes a simple example for you 
to work through. 
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Using ABC you can convert any of your BASIC into a relocatable module 
with little extra effort. This effectively allows you to add applications and 
new * commands to your Archimedes for use when ever required. If you 
are unsure as to what a relocatable module is, consult the Archimedes 
Reference Guide for a full description. | 


Relocatable Modules are created using ABC Compiler Directives — more 
information on these can be found in Chapter Six of the ABC Reference 
Guide. A typical relocatable module directive would look like this in a BASIC 
source program: | 


100 REM {MODULE TITLE Toolkit} 


This is just one of the six directives available for use in the creation of 
relocatable modules — the full list is given in the following table: 


Function Directive 

The module's title {MODULE TITLE <string>} 

The version _ {MODULE VERSION <string>} 

The type {MODULE TYPE <type>} 

Module Command {MODULE COMMAND <string>(num) (num)} 
Help text {MODULE HELP <string>} 


Memory required {MODULE MEMORY = <num>} 


All ‘num's’ are in decimal. Hex values are not allowed and any ‘num’ that 
is preceded with &, will be assigned a value of zero. Strings must contain 
only alphanumeric characters. If they contain any other symbols then the 
error ‘String too long’ will be given. All Compiler Directives must be 
specified using uppercase — capital — letters only. 


Module Title and Version 


The version is appended automatically to the end of the module title, as is 
the date. The resulting string is printed up when the following commands 
are issued: 


*HELP COMMANDS 
*HELP MODULES 
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Module Type 
There are three different module types: 


e Application 
e Service 
. © Utility 


The most useful of these, and the most limited, is the Service module type. 
It is most useful because if an error is generated while it is running it will 
drop back the application that was running when it was called, ie, if called 
from BASIC then the error can be trapped by using ON ERROR. However it is 
limited because it cannot use any floating point operations, or any of the 
BASIC keywords which use floating point arithmetic, that is: 


ACS LOG 
ANS PI 
ATN ©’ “RAD 
COS RND 
DEG SIN 
EXP SOR 
INT TAN 
LN VAL 


If floating point arithmetic or any of the above keywords are needed then 
the Application or Utility module types should be used. However if errors 
are generated while either of these types of module are running they will 
drop back to Arthur. The effect of this is similar to that of typing gurt from 
BASIC, So errors generated in these modules cannot be trapped. 


An Application module will use the application workspace, ie, all the RAM 
which remains after being configured away, and when finished it will drop 
back to Arthur. The Service and Utility modules use their own ‘private’ 
workspace and will not therefore corrupt any of your user RAM. The 
relative merits of each module are listed below: 


Module Type Floating point Trappable Errors Uses own RAM 


Application Yes No No 
Service No Yes Yes 
Utility Yes No Yes 


Module Command 

This is the command that will invoke the module. The command string 
should not contain any spaces or characters above 127 or below 31, in 
otherwords only alphanumeric characters. Any module command can be 
passed a number of parameters and the maximum and minimum number 
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of parameters you want passed to the module can be specified. If a fixed 
number of parameters are always required then only specify the minimum 
number of parameters. For example: 


REM {MODULE COMMAND FIXED 3} 


This directive will always require you to pass three parameters. If some of 
the parameters are optional then you should specify the maximum and 
minimum number of parameters, eg: 


REM {MODULE COMMAND VARIABLE 3 5} 


This directive will allow you to type no fewer than three parameters, and 
no more than five. | 


Module Help 
This string is printed up when the command: 


*HELP <command> 
is issued, ie: 
*HELP CSAVE 


will give help on the CMOS save module (see Examples disc). 


Module Memory 


For modules which use their own RAM and not the application RAM, that is 
Service and Utility modules, you must specify how much RAM they will 
require when running. Usually it is possible to have a good guess how 
much they need. It’s simpler to overestimate than to spend time trying to 
work out exactly how much RAM the module will need. The way to work 
out how much RAM your module will require is a long and complex 
process, but goes roughly as follows: 


e First you must work out how many real variables you will need 
¢ Work out how many integer variables 

¢ How many string variables 

¢ How much RAM has been DiMmed for use with assembler, if any 


The table on the following page shows how many bytes are used for each 
type of variable, and you can therefore estimate how much variable space 
will be needed. 


Le 


ABC User Guide 


Variable type Number of bytes 
4 


Real 

Integer 4 

String Maximum possible length of string 
DIMS Amount of RAM dimensioned 


To this you must add the amount of RAM that will be required for LOCAL 
variables in procedures. As you can see this process will take a long time if 
you want an accurate figure. If, on the other hand, you can spare 512 bytes 
or so, then estimate very roughly how much will be required, and if the 
module gives an error when run, then you have probably assigned too 
little! 


How to Make a Module 


If you want to compile a BASIC program into a relocatable module: 
i. Decide what type it will be: 
| Application, Service, Utility 


Refer to the section Module Type to decide which is the best type 
for your program, eg: 


REM {MODULE TYPE UTILITY} 


es Append the list of Compiler Directives, shown at the start of this 
chapter, to the beginning of the program. There are a default set 
on the Examples Disc saved under the file name ‘Utility.:ModDirs’. 
If you are using the BASIC Editor then this file can be APPENDed 
(SHIFT-f2) to then end of your program, and then moved to the 
start of it. 


3. Set the name, version, command and help strings. 


REM {MODULE TITLE TestModule} © 

REM {MODULE VERSION 1.00} 

REM {MODULE COMMAND NEW} 

REM {MODULE HELP A new module command} 


4. Decide (or estimate) how much RAM your module will need. You 
do not need to specify this if your module is an Application Module. 


REM {MODULE MEMORY = 1024} 


“3 SAVE the BASIC source, and then compile it. See Chapters Six and 
seven if the module fails to compile or load. 
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A Simple Example 


Chapter 20 of the Reference Guide contains further examples of the 
relocatable module directives and more can be found on the ABC Examples 
disc. To show just how easy they are to produce it is possible to convert the 
‘Hello’ program into a module. Just type in this listing: 


10 REM >ModHello 


20 REM {MODULE TITLE HelloModule } 

30 REM {MODULE VERSION 1.00 } 

40 REM {MODULE TYPE SERVICE } 

50 REM {MODULE COMMAND Hello } 

60 REM {MODULE HELP Prints a nice greeting! } 
70 REM {MODULE MEMORY = 512 } 

80 


90 PRINT "Hello ABC User!" 


Save the source file and compile the program saving under a suitable 
filename, ie, ModE1100BJ. 


The module must now be loaded into the Relocatable Module Area (RMA). 
To do this type: *RMLOAD ModE1100BJ | 


To see the effect type: *Hello and watch the message appear. To see the 
module help message type: *Help Hello 


Of course this example module has no real use. However it does illustrate 
the techniques involved and the simplicity of module making! 


LINES 


Star commands are used to invoke module commands and quite often the * 
command may require extra information which would generally be typed 
after the command. For example the CSAVE module example on the ABC 
Examples disc (see README file) contains a module with the command 
*CSAVE which saves the current CMOS RAM settings to a named file. The 
name of that file must follow the command. For example: 


*CSAVE :0.CmosSet 


ABC provides a mechanism that allows the command line to be 
investigated so that information such as filenames can be extracted. This is 
done by assigning the * command string to the variable LINES. 


This string is like any other BASIC string variable, and can be treated as 
such. It can therefore be scanned to see how many parameters have been 
passed, and you can work out what they were. You can use this process of 
investigating LINES to make your module respond to more than one * 
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command. All you would have to do is look at the first parameter in LINE$ 
and respond accordingly, using a CASE .. ENDCASE, ie: 


100 
LAD 
20 
130 
140 
150 
160 
170 
180 
x90 
200 


NS=1 
WHILE MIDS (LINES,N%,1)="":N%$+=1:ENDWHILE 
REM Misses out leading spaces 


Start%=N% 

WHILE MIDS (LINES,N%,1)<>" " AND N%<LEN LINES:N%+=1:ENDWHILE 
Command$=MID$ (LINES, Start%, N$-1) 

REM We have now found the first word in the variable LINES 
CASE Commands OF 

WHEN "SAVE":PROCSave 

WHEN "LOAD" :PROCload 

ENDCASE 


Note that all the variables used in this example are integer or string 
variables, but not floating point, as to allow it to be incorporated in a 
Service type module. Lines 110 to 150 can be used to find out any remaining 
parameters. For a full example see the CMOS saver and loader programs 
supplied. 


Further details and examples on the compilation of relocatable modules 
can be found in Chapter 20 of the Reference Guide. 
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More often than not when an error is produced during compilation the 
fault will be quite obvious, and easily fixed. The BASIC errors are very 
similar to those the interpreter would produce when interpreting the 
program. So if the interpreter can run your program and it is well 
structured without containing any illegal keywords, (see the Reference 
Guide), then it should compile first time. 


- However, if an error does occurs you will be given the option of editing the 


program. If you take up the option ABC will drop you into the BASIC Editor 
with the source file already loaded and positioned at the erroneous line. It 
is probably a good idea to note down the error line, and the error message. 


If the compiler cannot, or does not, load the source program into the BASIC 
Editor then you can enter it manually, using f2. You can then use f4 to 
search for the line with the error statement. This is often a good idea, as 
you can then use next match, f7, to see if this error occurs anywhere else in 
the program. 


For ease of reference error messages are arranged alphabetically under 
the following headings: 


e Error Messages —- General ¢ Assembly Language Errors 
e Module Related Errors e Warnings 


Error Messages 


The following section contains a complete list of the error messages which 
the compiler produces and an explanation of what they mean. Some are 
obviously more precise about the fault than others. 


Array elements are not allowed as control variables 


A FOR loop with an array element as the control variable was found. For 
example: 


FOR ASti)=1 TO IV i... NEAT 
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Array has <nnn> dimensions » 
You have tried to assign to an array element which doesn’t exist. For 
example: 


DEM A% (10) 
A% (1000) =A 


Attempt to divide by constant zero 


The constant optimiser has spotted a deliberate division by zero. If the 
program needs to cause an error it should use the ERROR statement. 


Attempt to nest PROC/ FN definitions 


The compiler came across the symbol DEF whilst still compiling the body of 
a procedure or function. This usually happens if you’ve missed out an 
ENDPROC or = in a previous part of the program. For example: 


DEF PROClevell 
ENDPROC 
DEF PROClevel2 


DEF FNLevel3 
=error 


Bad array 
A malformed array reference was found, for example: 


<NAME> has <nnn> dimensions 


An array reference in an expression was found to have the wrong number 
of subscripts. 


Bad array DIM 
A malformed DIM statement was encountered. 


Bad data type 
The data type of the object is not suitable for the operation requested. 


Bad expression type 
The expression was not of the correct data type for this operation. 


Bad factor type 


This is a low-level error from the compiler. It means that a factor (that is 
part of an expression) was not of the correct data type for the operation 
being used. 
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Bad formal parameter type 
One of the parameters of a function or procedure is not a variable, ie, 
DEF PROCdo (FNerr) 


The formal parameters of a procedure or function must be something 
which can be made LOCAL, for instance, a simple variable. 


Bad string 
A string has been encountered which is badly formed. 


Bad type in indirection 
The data-type of an object used in conjunction with one of the indirection 
operators (!1?$) is unacceptable. The only valid data-types are strings, 


integer and floating point. 

Bad <>= class operator 

A malformed comparison or shift operator was found. For example: 
IF A><B THEN . 


Can’t indirect from a string 


An operation of the form A$!4 was found. The operation N%!4 is valid 
however. 


Can't subtract strings 


You cannot remove one string from another using the — operator. To do 
this you should use a combination of INSTR(, MID$( and LEFT$(, eg: | 


AS="12345He11067890" 
BS="Hello" 


S$=LEFTS$ (A$, INSTR (A$, B$) -1) +MIDS$ (A$, INSTR (A$, B$) +LEN BS) 
CASE <expr> OF must be at the end of a line 
The language definition states that the OF must be the last non-space item 
on a line. | 


Flags must be numeric 


A SYS or CALL was used to return the flags, but the return variable was not 
an integer, or floating point. For example: 


CALL code TO ;AS$S 


a 


ABC User Guide 


Incorrect number of arguments 


A keyword or function has been used with an incorrect number of 
arguments. For example: 


CIRCLE 100,100 


MID$ needs at least 2 parameters 


The wrong number of parameters were given or the brackets are in the 
wrong place. 


Mistake 


The compiler reached the end of a statement and found that the next 
symbol was not the end of the line, a colon, or an ELSE statement. It was 
therefore ruled to be a mistake. For example: 


PRINT "Press a key” A=GET 


Here a colon is missing before A=GET. 


No such FN 
The compiler cannot find a function of the name given. 


No such PROC 
The compiler cannot find a PROCedure of the name given. 


No such variable 


The compiler ‘could not find either a LOCAL variable belonging to this 
procedure or a global variable with the correct name. See the ABC 
Reference Guide on Scope Rules. 


Should this be TOP 


The keyword TO was found in an expression. It could have been followed by 
a letter P to make TOP, but it wasn’t. 


Stack error 


The compiler has managed to lose track of various pointers and has 
corrupted memory contents. 


Syntax error 
The compiler could not make sense of the source line at all. 
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There is no line <nnnn> 


The line number specified after a GOTO, GOSUB, RESTORE or THEN cannot be 
found within the program. This error would (eventually) stop the program 
working under the interpreter. Of course RENUMBER would detect it as 
well. 


This operation is not supported 
A keyword was found which is not supported by the compiler. 


Too long 


A symbol of more than 255 characters was found. This can happen when 
using STRINGS, or joining two strings together etc. For example: 


AS=STRINGS (1023,"1234567890") 


It can also happen if your BASIC program source code becomes corrupted, 
but this is unlikely. 
Type mismatch 
The data type of two objects are incompatible. For example: 
A%="STRING" 


Type mismatch — number needed 
The data type of the object must be integer or floating point, eg: 
A="123" 


Type mismatch — string needed 
The data type of the object must be a string, eg: 


AS=10 


Unable to resolve definitions 


This means that after two passes, the compiler could not determine the 
data types of all the objects. | 


Unclosed < xx> 


A badly nested or unclosed structure was found. For example: 


CASE 2 °OF 
REPEAT 
ENDCASE 
UNTIL TRUE 
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Unknown type 
An object has been found whose datam type is unknown. 


Unknown object(s) found 


This means that at the end of pass one, the compiler had not seen 
definitions for all the functions and procedures used or that some variables 
had been referred to without ever being assigned a value, ie: 


10 PROCnothing 
20 END 


Variable required 
A variable, as opposed to a constant, in a PROCedure definition was 
required. For example: 


DEF PROCerror (10,20) 


Wrong type of parameter _ 
The parameter being passed to a PROCedure of function was of a different 
type to the one expected. For example: 


PROCEGrOr ("Error , 10) 

END 

DEF PROCerror (A%, errors) 
~ ENDPROC 


<name> not an array 


A variable identifier was found followed by a bracket. There was no array 
of this name. For example: 


MID (AS, 2,1) 


<type> expected 


This means that the compiler was expecting to find an expression of the 
type stated, but found a different one. For example, string expected. 


Assembly Language Errors 
Bad assembler instruction 


The compiler has encountered an unrecognisable assembly language 
statement. 
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Bad branch instruction 


A branch or branch-link instruction was found to be incorrectly formed. For 
example: 


BL RO+ 


Bad condition code 


An assembler statement with a malformed condition code was found. For 
example: 


ADDQW RO,RO,R1 


Bad EQU 


An EQU assembler directive was found to be incorrectly formed. For 
example: 


EQUA “Hello” 


Bad option 
The options for a mnemonic were malformed, or incorrect. For example: 


STMHIF R13!,{RO-R12,R14} LDRIA_ RQ, [RO] 


Module Related Error Messages 


FP ops not allowed in service mode 


The module type SERVICE cannot use the floating point opcodes. Therefore 
any reference to real values or variables is disallowed. Refer to the section 
on Modules for more information on the restriction on keywords. 


maxargs must be >= minargs 


If you want to limit the number of arguments that you can pass to a module 
by specifying the maximum and minimum number of arguments, then you 
must remember to specify a maximum limit of more than the minimum, le: 


REM {MODULE COMMAND Range 5 3} 


means the maximum number of arguments you can pass is three, where as 
the minimum number of parameters is five. 


Must be >= 0 


This will occur when you specify the amount of memory needed during the 
execution of a module to be less than or equal to 0, which is obviously silly. 
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0 to 255 only 


This error results from a MODULE Command Directive which is 
malformed, or which requests a number of arguments outside the 
permitted range. The range is 0 to 255. 


Warnings 
Warnings are given during compilation when errors occur but are not 
necessarily fatal and allow the compiler to continue, at least for a while! 


Attempt to CALL BBC MOS entry point 


This means that a CALL or USR was found with an address which the 
interpreter would have trapped as a call to a BBC Micro MOS routine, eg: 


A%$=138:X%=0:Y%=65:CALL &FFF4 


FN<name> is not defined & PROC<name> is not defined 


No definition of this function or procedure has been found. This warning is 
given but an error will occur later! | 


FN<name> has unknown type 
This function has been defined, but the type it returns remains unknown. 


Structures must be properly nested 


This error will be given if the compiler finds badly nested structures in the 
program. For example: 


REPEAT 
FOR N%=1 TO 10 
UNTIL FALSE 


There is no NEXT statement and so the compiler will give this error message 
when it sees the UNTIL. This error is also given if more than one exit is 
given from a structure. For example: 


DEF PROCdo 
IF x%=0 THEN ENDPROC 
ENDPROC | 
See the section ‘Hints and Tips' for more details on program structure. 
<name> not defined 


This variable name was used without there being an assignment to it. 
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Once the program is compiled things can still go wrong even if the 
program runs under the interpreter. The main reasons for this are as 
follows. 


Undefined Instruction 


A common mistake is to forget to load the Floating Point Emulator 
package. This is normally done by the command file however issuing a 
command such as *RMCLEAR will remove it. If you try to run ABC without 
the FPE present an ‘Undefined instruction’ error will occur when any 
floating point operation is used. 


To load the FPE, QUIT from BASIC to the Arthur supervisor prompt and uke 
the ABC working disc in drive 0. Type: 


*MOUNT 0 
*FPE 


Then try running the program again. 


Failed to Initialise Workspace 


This is caused under extreme circumstances where there is not enough RAM 
to start running the program. If this happens you will have to either: 


1. Reduce the amount of RAM required, for example by reducing the size 
of arrays 


2. Provide the program with more memory. This can be done by 
adjusting the configuration of the machine to release RAM from the 
system. For example, the amount of screen memory might be reduced 
to a lower level if the program does not rogers a high-resolution 
colour display. 
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Heap Full 


This also means that the program has run out of memory. The ‘heap’ is an 
area of memory which is used to store all the arrays, global variables and 
strings used in the program. Again, this problem can be fixed by reducing 
the demand or by increasing the supply. It is possible to use the HEAP 
Compiler Directive to set the amount of HEAP space which will be claimed. 
See Chapter Six of the ABC Reference Guide for full details. 


Stack Overflow 


Again, you have run out of memory. The stack, which is used for local 
variables and for recording the sequence of PROC or FN calls has grown so 
far that it has run into the Heap and cannot grow any more. The solutions 
are, of course to provide more RAM, to reduce the size of the HEAP or to 
reduce the requirement fcr stack space. The STACK directive can be used to 
help this situation. See Chapter Six of the ABC Reference Guide for 
details. 
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Compatibility 


Most BASIC programs will compile under ABC with little or no modfica- 
tions. However, total compatibility is not possible and the following 
sections have been written to guide you in writing programs which are 
compatible with both systems. 


Structure Rules 


ABC determines the structural relationships between the different parts of 
your program during compilation. It cannot leave this until the program is 
run. For this reason, certain rules concerning the structure of the program 
must be adhered to. The most important rule is that there must be must be a 
one-to-one relationship between the starts and ends of structures. The 


_most obvious example is that every REPEAT must have a matching UNTIL 


and so on for all of the other structures. 


This is not too hard to achieve — indeed the interpreter already makes this 
restric-tion for CASE statements and for multi-line IF...THEN...ELSE...ENDIF 
structures. However, there are two very important structures which have 
been used traditionally in a manner which the compiler will not accept. 
These are DEFPROC...ENDPROC and DEFFN...=<expr>. 


ABC insists that there is only one ENDPROC for every DEFPROC. This may 
cause many programs to give errors when they are compiled since it is 
quite common to find that PROCs have a number of different exits. 


The most brutal way to deal with this is to use the BASIC Editor to convert 
the ENDPROCs to GOTOs to an line with a single ENDPROC at the end of each 
procedure. This can be done using the GLOBAL REPLACE feature (f5) together 
with limits (set by pressing CTRL-L twice at the top and twice at the bottom 
of the area to be affected. 


For example the procedure: 
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1000 DEF PROCddle 

Ae be hee 

1020 IF X=0 THEN ENDPROC 
Da vk us 

1040 ENDPROC 


could be written as: 


1000 DEF PROCddle 

Sea cava 

1020 IF X=0 THEN GOTO 1040 
£030). 

1040 ENDPROC 


A better, more structured, way to resolve this problem is to convert the 
program to use the multi-line IF...THEN...ELSE...ENDIF 


The above example would then become: 


1000 DEF PROCddle 

re ee 

1020 IF X=0 THEN 

1025 ELSE 

9 Ah ee 

1035 ENDIF 

1040 ENDPROC 
In the long run this will be the better way to do it because the GOTOs get to 
be rather confusing after a while! 


Scope Rules 


Another important thing about ABC is the meaning of LOCAL variables. In 
common with other compiled systems, LOCAL variables really are local to 
the procedure in which they are declared. This means that another 
procedure cannot use them, even if it is called from within the first 
procedure. This means that you will have to pass the values of everything 
which is needed as parameters, unless they are held in global variables. 


A problem can occur if there is a global variable called, for instance, ‘N’ as 
well as a LOCAL variable called ‘N’. If another procedure tries to use the 
value of ‘N’ which does it refer to? ABC always takes it to refer to the 
global variable. The Acorn BASIC interpreter will take it to mean the global 
if the procedure is called from the main program but will use the local 
version if the procedure is called from the other procedure. The compiler 
cannot warn you about this because the program looks perfectly valid. 
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The way to avoid this is to use different names for global and local 
variables. There can then be no ambiguity and the compiler will be able to 
tell if you are asking to get at another procedure's local variables. 


Use of Compiler Directives 


The Compiler Directives COMPILE and NOCOMPILE can be used in a number 
of ways to make programs which overcome the differences between the 
compiled and interpreted forms of the language. 


For example, it is possible to provide two definitions of a procedure one 
which suits the interpreter and one for the compiler. The interpreter will 
only look at the first definition in the program. The compiler can be made 
to skip this and only compile the second. 


999 REM { NOCOMPILE } 
1000 DEF PROCwrite 
LOL vis 
1020 ENDPROC 
1999 REM { COMPILE } 
2000 DEF PROCwrite 
Aa Ee imeem 
2020 ENDPROC 
A number of other tricks like this are given in the following sections. 


Manifest Constants 


To make compiled programs even faster, you can define ‘manifest 
constants’ instead of variables. These are essentially constant values which 
can be referred to by name. The names of these constants look just like 
those of variables and can be used in the same way as a variable inside 
expressions. 


Use of these constants will save memory since they do not need to have any 
memory space reserved for them. The compiler can also generate very 
much shorter and faster code when your programs use constants. 


For example: 


10 DEF xside% = 4 

20 DEF yside% = 5 

39 Saati 

40 area% = xside%*yside% 
ee is wails 


This program uses DEF to define two manifest constants ‘xside%’ and 
‘yside%’. These are then used later in the program. If variables were used 
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then the compiler would produce code to load both xside% and yside% 
followed by a multiply operation. Since we have used constants the 
compiler does the multiplication ‘on the spot’ and reduces the code at 
compile time to the equivalent of area%=20. No multiplication instruction 
is generated. 


It is also comforting to know that your program cannot accidentally 
change the values of these important quantities! 


Floating Point 


A major difference between the two systems in the way in which they 
handle floating point numbers. The floating point provided by the Acorn 
Floating Point Emulator is used by ABC. It is less accurate than the package 
built into the BASIC interpreter. This can cause some programs to get into 
difficulties when the larger degrees of rounding errors build up to such an 
extent that they become significant. 


@% and Five-byte Floating Point 


The Acorn BASIC interpreter stores all its floating point numbers using five 
bytes. On the otherhand, the Floating Point Emulator stores them using 
only four bytes. This can cause problems. For example, if you try to create 
data files using a compiled program and then try to access the file with an 
interpreted BASIC program. The data files will contain the numbers in four- 
byte format and the program will not be able to understand them. This 
problem can be avoided using a specially provided flag bit. 


If you set bit 24 of the print control variable @% in a compiled program, all 
output to datafiles of floating point numbers will be done in the five-byte 
format. This enables full compatibility with the interpreter. 


Compiled programs will read data files in either format and carry out the 
necessary conversion automatically. 


Floating Point Indirection 


Because floating point indirection only transfers four bytes instead of five, 
you may find it convenient to allocate a multiple of four bytes of space in 
compiled programs but a multiple of five bytes when interpreting. Also you 
would need to calculate the offsets into a table of indirected floating point 
numbers using a different factor. (This also applies to calculating PTR 
values in data files.) 
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Hints and Tips 


A neat way to do this is to use the COMPILE and NOCOMPILE directives 
together with the manifest constant mechanism to write a program which 
runs both under the compiled and interpreted systems. 


For example: 


110 REM { NOCOMPILE } 
120 floatsize%=5 

130 REM { COMPILE } 
140 DEF floatsize% = 4 


Under the interpreter lines 110,130 and 140 are ignored and so a factor of 
five is used. The compiler directives cause line 120 to be ignored and line 
140 defines a manifest constant — value four — for the size. 


CALL and USR 


Under ABC the CALL statement does not export the values of A%,B%,...H% 
in registers. Instead you must provide a list of expressions whose values 
will be passed in the registers. This can easily be circumnavigated by using 
the Compiler Directives as shown above. Define two procedures, one 
which does the CALL in a manner suitable for the interpreter and one which | 
is suitable for the compiler. If the one for the interpreter is placed first but 
delimited with REM {NOCOMPILE} before it and REM{COMPILE} after, the 
program will work under both systems. 


The same applies to the use of USR. 


BASIC Programs as Text files 


If you prefer to use a text-based editor such as TWIN to write your BASIC 
programs rather than the BASIC Editor then you must remember to tokenise 
the program before submitting it to the compiler. 


Using TWIN, the simplest way to do this is to return to BASIC with the file 
loaded. Load the file into TWIN and the press SHIFT-f4. TWIN will prompt 
with ‘Return to language’. Type BAsIc and press RETURN. TWIN will hand 
the program over to BASIC using a special handshake to tell BASIC to accept 
the in-RAM file. BASIC will put line numbers on and re-tokenise the text as 
required. You should then save the program before submitting it to the 
compiler. | 
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If you as using some other text editor, or have no text editor but have 
somehow aquired a program in text form, you can easily get it retokenised. 


Assuming the name of the text file is ‘TextProg’ type: 
*BASIC -LOAD TextProg 


BASIC will load the file and automatically convert it to a fully tokenised 
program complete with line numbers. 


Embedded Assembly Language 


Just like the BASIC interpreter, ABC allows ARM assembly language 
statements to be embedded within BASIC programs. This may seem 
confusing at first but it is quite logical. The simple fact is that the compiled 
program with embedded assembler should behave exactly the same as the 
source BASIC program running as normal. That is, when the program is run 
it constucts a fragment of machine code in memory as directed by P% in the 
usual way. 


There is no point using ABC to compile programs which are primarily 
assembly language, one might as well use the interpreter. However, many 
BASIC programs contain small sections of assembler and it is very conven- 
ient to compile the program without having to separate the assembly lang- 
uage sections. Often emdedded assembly language routines are used for 
speed critical subroutines, hopefully ABC will speed up the rest of the BASIC 
program so that the overall performance of the program is improved. 


Registers 


It is necessary to define the variable RO,R1,... R14 and Pc explicitly under 
ABC if they are used in assembly language statements. You could include 
lines at the start of the program to define them all. For example: 


10 RO=0:R1=1:R2=2:R3=3:R4=4:R5=5:R6=6:R7=7:R8=8 
20 R9=9:R10=10:R11=11:R12=12:R13=14:R14=14 
39 PCe#is5 


This could also be done using manifest constants. For example: 


10 DEF RO 
20 DEF Rl 
30 DEF R2 
40 DEF R3 
50 DEF R14 = 14 
60 DEF PC = 


CW KO. €) 
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Default OPT Setting 


There is a Compiler Directive which allows you to change the action of OPT 
and opening square brackets in the assembler. The directive: 


REM {NOOPT} 


makes the compiler ignore all subsequent OPT directives in the assembler, it 
also prevents the implicit OPT 3 which is given by '['. This can be used to 
make it unnecessary to repeatedly give the OPT setting in a program which 
contains lots of separarte sections of assembly language. This is more than 
just a typing convenience, it causes less code to be generated. The ABC 
compiler (which is written in BASIC and compiles itself!) uses this directive 
to good effect, the compiler is 18k shorter as a result! 
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If you are wondering how ABC converts a BASIC program into machine 
code, or you would like to optimise the code it produces then read on. 
Please note: this chapter is not for the faint hearted as it is quite technical. 


Contained on the Examples disc is a disassembler program which will help 
you to examine ABC object code. However, producing a straight assembly 
listing of the object code would be of very little use to you. Therefore the 
disassembler is semi-intelligent which will make your problems slightly less 
daunting. There are four main problems which are encountered, only one 
of which have been overcome for reasons which will become apparent. 


The first problem is the inability of a disassembly program to distinguish 
between data and program. There are ways around this, but they are not 
always successful, and once a mistake is made the output is totally useless. 
That said it could be implemented if required by first looking for where the 
object code starts. Machine code can be set into action using two different 
methods. Firstly by using the B or BL mnemonics, or using the PC as the 
destination register in some mnemonics. If all programs used the former 
method then it would be a relatively simple problem to solve. However the 
latter is quite often used and would totally confuse the disassembler. 


The principle behind determining if you are disassembling data or program 
is as follows. Any piece of machine code will be branched to and will return 
by using: 


MOV PC,R14 
or alternatively: 
LDMFD R13!,{...,R14} 


In theory then any code which is not branched to is therefore DATA and 
should not be disassembled into mnemonics, but left as EQUDs. 


The second problem is how to determine which parts of the code are 
branched to, and therefore where the labels should be inserted. This was a 
very easy problem to overcome. 
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The Disassembler 


The disassembler first goes through the code and finds all branch 
instructions. It works out the location of the label and remembers where it 
is branched from. The labels are sorted into order as they are found. 


As compiled programs are re-locatable there are no PC relative addresses 
for loading and storing data (eg, LDR Ro,[PC,#160]). Instead ABC uses a four 
instruction ADR command to calculate it's addresses. It is very difficult to 


decide if an instruction is part of this extended ADR command or not. 


Therefore there are no labels for data, only for program. 


The last problem is that the OS disassemble SWI can return the same 
mnemonic for two (or more) different words though this has only been 
found with the MOV and MVN mnemonics. This is because they only use two 
cegisters with the third register being ignored. This results in the words 


-&01FD8000 and &01F08000 returning the same mnemonic (you may 


realise that &1FD8000 is the start of screen address in Mode 13, so any 
direct reference to this results in the wrong value when re-assembled). To 
get round this there is a fix to ensure that if the high nibble of the low byte 
of the high word is non-zero the instruction is not disassembled but EQUDed: 
instead. 


Compiled programs use the floating point mnemonics which the BASIC in- 
line interpreter does not recognise. However there are many public domain 
programs which will allow you to use the floating point mnemonics by 
replacing them with function calls. As each different public domain 
program uses it's own conventions for handling these mnemonics no firm 
examples can be given. If the disassembler comes across any floating point 
reference it replaces it with the text FNfloat(" followed by the disassem- 
bled mnemonic. From this you can derive all the information you need. 


The compiled programs are relocatable (ie, they can run from any word 
aligned address) so any reference to locations within the object code are 
done by using an extended version of ADR. This command adds or subtracts 
a twelve bit value from the program counter to derive the address of the 
label. The extended version that ABC uses takes three instructions. Firstly 
the low byte of the low word is calculated, then the high byte of the low 


word is added to that and lastly the low byte of the high word is added. 5o 


for every relative offset calculation there are three ADD or three SUB 
instructions. It is relatively easy to spot these. 


The assembly listings are optimised to a very small extent to reduce the size 
of them! The comments which the OS disassembler sometimes adds to 
instructions have also been removed. If the disassembler finds many 
identical mnemonics in a row then it will use a FOR ... NEXT loop instead of 
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repeating the same mnemonic over and over oan. eg, if the source code 
looked something like this: 

ANDEQ RO,RO,RO 

ANDEQ R0,RO,RO 

ANDEQ RO,RO,RO 

ANDEQ RO,RO,RO 

ANDEQ R0,RO0,RO 

ANDEQ R0,RO,RO 

ANDEQ RO,RO,RO 


Then the disassembler will generate the following: 
]:FOR Q%=0 TO 6: [OPT OPT 


ANDEQ RO,RO,RO 
]:NEXT: [OPT OPTS 


ABC Object Format © 


Object code created with ABC is constructed in the following way: 
Start Branch to initialisation and main code 


Scratch area _ This is used when issuing SyS / SWI calls, and for creating 
the parameters which are passed to procedures 


Branch lookup This lookup table is used to index both library areas 


Library code This is the main library code area. All strings, the text of 
any string which is used in the program will be held here 


Line no. offsets This is a lookup of line numbers to locations in the 
compiled code. This is used if you use any calculated GOTO 
statements ,eg, GOTO 1000+age%*10 


Main code The main code branched too 
Library code This is additional 'tidy up' library code 


The compiled programs use register R13 as a full descending stack pointer. 
Register R12 is used to point to global variables. Register R11 is used to 
point to LOCAL variables and PROCedure invoked variables. Registers RO 
and R1 are used mainly for arithmetic operations. Any additional code you 
add must therefore preserve registers R11, R12 and R13 for obvious 
reasons. 
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Down to Work 


The disassembler can be found in the directory DISASS. This also contains a 
very short BASIC program called ‘Hello’. This program will be used to 
explain how to use the disassembler and demonstrate how to investigate 
the assembly listings. Compile the ‘Hello’ program and save it under the 
name ‘HelloObj’. 


The files produced by the disassembler are large and therefore it is wise to 
copy the disassembler to its own disc — copy the ‘HelloObj’ program here 
as well. Run the disassembler as follows: 


*BASIC 
*!IDISS 


When prompted enter the following details: 


HelloObj for the source name 
ASS for the listing name. 


The disassembly will take about ten minutes. As the program is working it 
will display label location address on screen. Once it has converted the 
code into mnemonics these are *SPOOLed out to disc (which must therefore 
be present) and then *EXECed back into memory at which point the BASIC 
Editor is invoked. Once this has been done drop out of the Editor (SHIFT-f4) 
and type RUN. | 


At this point an error will be generated (‘Duplicate register in multiply in 
line 770’). This error is hard to trap, and again is a problem (noi a fault) 
with the disassembler SWI. Replace the erroneous line with: : 


770 MULEQ RO, PC,R0O 


RUN the program again. This time it should assemble without error. If you 
type: 


CALL code 
it should run as expected. 
Murder She Wrote 


We cari now start to investigate the listing produced by the disassembler. 
Go back into the Editor and search and edit (4) for: 


Label0153 
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The first occurrence is the very first instruction in the program which 
branches to the main code and initialisation sections. This is followed by a 
large amount of data in the form of: 


ANDEQ RO,RO,RO 
in a FOR ... NEXT loop. 


This will in fact be in all programs, but the size may change depending on 
the size of the HEAP and STACK. If you use the page down key you will soon 
come across a long list of branch instructions. Each instruction branches to 
a different Library routine. You may notice that some of these are preceded 
by a label name, eg: 


.-Label0Q001 B Label0042 


Any branch which has a label in front of it indicates that this particular 
library routine is used in the program. If you now search for: 


-Label0042 


you will see that this calls the Sound_QSchedule sSwI, and is therefore 
obviously is used by the SOUND statement in the 'Hello' BASIC program. We 
can now find out from where Lable0001 is branched to. Again use f4 to 
search for Label0001 It will first find the Label itself so press f7 to find the 
next occurrence. This may take some time. You may now be able to 
ascertain where the FOR .. NEXT loop is perhaps even change it. 


It is a simple matter to change the SOUND statement. The lines just before 
BL Label0001 (35540) set up then necessary registers for the library routine. 
It should be obvious that R2 is used for the volume (MVN R2,#&0E) and 
that R1 is used for the channel number. If you change line 35520 to 


MOV Rl, #2 


then drop back to BASIC (SHIFT-f4) and type the following: 


VOICES 2 
*CHANNELVOICE 2 8 
RUN 

CALL code 


you will hear channel two playing percussion. 


Warning: Be careful when inserting extra instructions into the assembly 
listing. You will have to make sure that you do not corrupt any extended 
ADR instructions. Also be very careful about modifying any of the disc 
library routines, the results could be fatal. 
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